| 1 | /* $NetBSD: postmulti.c,v 1.2 2017/02/14 01:16:47 christos Exp $ */ |
| 2 | |
| 3 | /*++ |
| 4 | /* NAME |
| 5 | /* postmulti 1 |
| 6 | /* SUMMARY |
| 7 | /* Postfix multi-instance manager |
| 8 | /* SYNOPSIS |
| 9 | /* .fi |
| 10 | /* .ti -4 |
| 11 | /* \fBEnabling multi-instance management:\fR |
| 12 | /* |
| 13 | /* \fBpostmulti\fR \fB-e init\fR [\fB-v\fR] |
| 14 | /* |
| 15 | /* .ti -4 |
| 16 | /* \fBIterator mode:\fR |
| 17 | /* |
| 18 | /* \fBpostmulti\fR \fB-l\fR [\fB-aRv\fR] [\fB-g \fIgroup\fR] |
| 19 | /* [\fB-i \fIname\fR] |
| 20 | /* |
| 21 | /* \fBpostmulti\fR \fB-p\fR [\fB-av\fR] [\fB-g \fIgroup\fR] |
| 22 | /* [\fB-i \fIname\fR] \fIcommand...\fR |
| 23 | /* |
| 24 | /* \fBpostmulti\fR \fB-x\fR [\fB-aRv\fR] [\fB-g \fIgroup\fR] |
| 25 | /* [\fB-i \fIname\fR] \fIcommand...\fR |
| 26 | /* |
| 27 | /* .ti -4 |
| 28 | /* \fBLife-cycle management:\fR |
| 29 | /* |
| 30 | /* \fBpostmulti\fR \fB-e create\fR [\fB-av\fR] |
| 31 | /* [\fB-g \fIgroup\fR] [\fB-i \fIname\fR] [\fB-G \fIgroup\fR] |
| 32 | /* [\fB-I \fIname\fR] [\fIparam=value\fR ...] |
| 33 | /* |
| 34 | /* \fBpostmulti\fR \fB-e import\fR [\fB-av\fR] |
| 35 | /* [\fB-g \fIgroup\fR] [\fB-i \fIname\fR] [\fB-G \fIgroup\fR] |
| 36 | /* [\fB-I \fIname\fR] [\fBconfig_directory=\fI/path\fR] |
| 37 | /* |
| 38 | /* \fBpostmulti\fR \fB-e destroy\fR [\fB-v\fR] \fB-i \fIname\fR |
| 39 | /* |
| 40 | /* \fBpostmulti\fR \fB-e deport\fR [\fB-v\fR] \fB-i \fIname\fR |
| 41 | /* |
| 42 | /* \fBpostmulti\fR \fB-e enable\fR [\fB-v\fR] \fB-i \fIname\fR |
| 43 | /* |
| 44 | /* \fBpostmulti\fR \fB-e disable\fR [\fB-v\fR] \fB-i \fIname\fR |
| 45 | /* |
| 46 | /* \fBpostmulti\fR \fB-e assign\fR [\fB-v\fR] \fB-i \fIname\fR |
| 47 | /* [\fB-I \fIname\fR] [-G \fIgroup\fR] |
| 48 | /* DESCRIPTION |
| 49 | /* The \fBpostmulti\fR(1) command allows a Postfix administrator |
| 50 | /* to manage multiple Postfix instances on a single host. |
| 51 | /* |
| 52 | /* \fBpostmulti\fR(1) implements two fundamental modes of |
| 53 | /* operation. In \fBiterator\fR mode, it executes the same |
| 54 | /* command for multiple Postfix instances. In \fBlife-cycle |
| 55 | /* management\fR mode, it adds or deletes one instance, or |
| 56 | /* changes the multi-instance status of one instance. |
| 57 | /* |
| 58 | /* Each mode of operation has its own command syntax. For this |
| 59 | /* reason, each mode is documented in separate sections below. |
| 60 | /* BACKGROUND |
| 61 | /* .ad |
| 62 | /* .fi |
| 63 | /* A multi-instance configuration consists of one primary |
| 64 | /* Postfix instance, and one or more secondary instances whose |
| 65 | /* configuration directory pathnames are recorded in the primary |
| 66 | /* instance's main.cf file. Postfix instances share program |
| 67 | /* files and documentation, but have their own configuration, |
| 68 | /* queue and data directories. |
| 69 | /* |
| 70 | /* Currently, only the default Postfix instance can be used |
| 71 | /* as primary instance in a multi-instance configuration. The |
| 72 | /* \fBpostmulti\fR(1) command does not currently support a \fB-c\fR |
| 73 | /* option to select an alternative primary instance, and exits |
| 74 | /* with a fatal error if the \fBMAIL_CONFIG\fR environment |
| 75 | /* variable is set to a non-default configuration directory. |
| 76 | /* |
| 77 | /* See the MULTI_INSTANCE_README tutorial for a more detailed |
| 78 | /* discussion of multi-instance management with \fBpostmulti\fR(1). |
| 79 | /* ITERATOR MODE |
| 80 | /* .ad |
| 81 | /* .fi |
| 82 | /* In iterator mode, \fBpostmulti\fR performs the same operation |
| 83 | /* on all Postfix instances in turn. |
| 84 | /* |
| 85 | /* If multi-instance support is not enabled, the requested |
| 86 | /* command is performed just for the primary instance. |
| 87 | /* .PP |
| 88 | /* Iterator mode implements the following command options: |
| 89 | /* .SH "Instance selection" |
| 90 | /* .IP \fB-a\fR |
| 91 | /* Perform the operation on all instances. This is the default. |
| 92 | /* .IP "\fB-g \fIgroup\fR" |
| 93 | /* Perform the operation only for members of the named \fIgroup\fR. |
| 94 | /* .IP "\fB-i \fIname\fR" |
| 95 | /* Perform the operation only for the instance with the specified |
| 96 | /* \fIname\fR. You can specify either the instance name |
| 97 | /* or the absolute pathname of the instance's configuration |
| 98 | /* directory. Specify "-" to select the primary Postfix instance. |
| 99 | /* .IP \fB-R\fR |
| 100 | /* Reverse the iteration order. This may be appropriate when |
| 101 | /* updating a multi-instance system, where "sink" instances |
| 102 | /* are started before "source" instances. |
| 103 | /* .sp |
| 104 | /* This option cannot be used with \fB-p\fR. |
| 105 | /* .SH "List mode" |
| 106 | /* .IP \fB-l\fR |
| 107 | /* List Postfix instances with their instance name, instance |
| 108 | /* group name, enable/disable status and configuration directory. |
| 109 | /* .SH "Postfix-wrapper mode" |
| 110 | /* .IP \fB-p\fR |
| 111 | /* Invoke \fBpostfix(1)\fR to execute the specified \fIcommand\fR. |
| 112 | /* This option implements the \fBpostfix-wrapper\fR(5) interface. |
| 113 | /* .RS |
| 114 | /* .IP \(bu |
| 115 | /* With "start"-like commands, "postfix check" is executed for |
| 116 | /* instances that are not enabled. The full list of commands |
| 117 | /* is specified with the postmulti_start_commands parameter. |
| 118 | /* .IP \(bu |
| 119 | /* With "stop"-like commands, the iteration order is reversed, |
| 120 | /* and disabled instances are skipped. The full list of commands |
| 121 | /* is specified with the postmulti_stop_commands parameter. |
| 122 | /* .IP \(bu |
| 123 | /* With "reload" and other commands that require a started |
| 124 | /* instance, disabled instances are skipped. The full list of |
| 125 | /* commands is specified with the postmulti_control_commands |
| 126 | /* parameter. |
| 127 | /* .IP \(bu |
| 128 | /* With "status" and other commands that don't require a started |
| 129 | /* instance, the command is executed for all instances. |
| 130 | /* .RE |
| 131 | /* .IP |
| 132 | /* The \fB-p\fR option can also be used interactively to |
| 133 | /* start/stop/etc. a named instance or instance group. For |
| 134 | /* example, to start just the instances in the group "msa", |
| 135 | /* invoke \fBpostmulti\fR(1) as follows: |
| 136 | /* .RS |
| 137 | /* .IP |
| 138 | /* # postmulti -g msa -p start |
| 139 | /* .RE |
| 140 | /* .SH "Command mode" |
| 141 | /* .IP \fB-x\fR |
| 142 | /* Execute the specified \fIcommand\fR for all Postfix instances. |
| 143 | /* The command runs with appropriate environment settings for |
| 144 | /* MAIL_CONFIG, command_directory, daemon_directory, |
| 145 | /* config_directory, queue_directory, data_directory, |
| 146 | /* multi_instance_name, multi_instance_group and |
| 147 | /* multi_instance_enable. |
| 148 | /* .SH "Other options" |
| 149 | /* .IP \fB-v\fR |
| 150 | /* Enable verbose logging for debugging purposes. Multiple |
| 151 | /* \fB-v\fR options make the software increasingly verbose. |
| 152 | /* LIFE-CYCLE MANAGEMENT MODE |
| 153 | /* .ad |
| 154 | /* .fi |
| 155 | /* With the \fB-e\fR option \fBpostmulti\fR(1) can be used to |
| 156 | /* add or delete a Postfix instance, and to manage the |
| 157 | /* multi-instance status of an existing instance. |
| 158 | /* .PP |
| 159 | /* The following options are implemented: |
| 160 | /* .SH "Existing instance selection" |
| 161 | /* .IP \fB-a\fR |
| 162 | /* When creating or importing an instance, place the new |
| 163 | /* instance at the front of the secondary instance list. |
| 164 | /* .IP "\fB-g \fIgroup\fR" |
| 165 | /* When creating or importing an instance, place the new |
| 166 | /* instance before the first secondary instance that is a |
| 167 | /* member of the specified group. |
| 168 | /* .IP "\fB-i \fIname\fR" |
| 169 | /* When creating or importing an instance, place the new |
| 170 | /* instance before the matching secondary instance. |
| 171 | /* .sp |
| 172 | /* With other life-cycle operations, apply the operation to |
| 173 | /* the named existing instance. Specify "-" to select the |
| 174 | /* primary Postfix instance. |
| 175 | /* .SH "New or existing instance name assignment" |
| 176 | /* .IP "\fB-I \fIname\fR" |
| 177 | /* Assign the specified instance \fIname\fR to an existing |
| 178 | /* instance, newly-created instance, or imported instance. |
| 179 | /* Instance |
| 180 | /* names other than "-" (which makes the instance "nameless") |
| 181 | /* must start with "postfix-". This restriction reduces the |
| 182 | /* likelihood of name collisions with system files. |
| 183 | /* .IP "\fB-G \fIgroup\fR" |
| 184 | /* Assign the specified \fIgroup\fR name to an existing instance |
| 185 | /* or to a newly created or imported instance. |
| 186 | /* .SH "Instance creation/deletion/status change" |
| 187 | /* .IP "\fB-e \fIaction\fR" |
| 188 | /* "Edit" managed instances. The following actions are supported: |
| 189 | /* .RS |
| 190 | /* .IP \fBinit\fR |
| 191 | /* This command is required before \fBpostmulti\fR(1) can be |
| 192 | /* used to manage Postfix instances. The "postmulti -e init" |
| 193 | /* command updates the primary instance's main.cf file by |
| 194 | /* setting: |
| 195 | /* .RS |
| 196 | /* .IP |
| 197 | /* .nf |
| 198 | /* multi_instance_wrapper = |
| 199 | /* ${command_directory}/postmulti -p -- |
| 200 | /* multi_instance_enable = yes |
| 201 | /* .fi |
| 202 | /* .RE |
| 203 | /* .IP |
| 204 | /* You can set these by other means if you prefer. |
| 205 | /* .IP \fBcreate\fR |
| 206 | /* Create a new Postfix instance and add it to the |
| 207 | /* multi_instance_directories parameter of the primary instance. |
| 208 | /* The "\fB-I \fIname\fR" option is recommended to give the |
| 209 | /* instance a short name that is used to construct default |
| 210 | /* values for the private directories of the new instance. The |
| 211 | /* "\fB-G \fIgroup\fR" option may be specified to assign the |
| 212 | /* instance to a group, otherwise, the new instance is not a |
| 213 | /* member of any groups. |
| 214 | /* .sp |
| 215 | /* The new instance main.cf is the stock main.cf with the |
| 216 | /* parameters that specify the locations of shared files cloned |
| 217 | /* from the primary instance. For "nameless" instances, you |
| 218 | /* should manually adjust "syslog_name" to yield a unique |
| 219 | /* "logtag" starting with "postfix-" that will uniquely identify |
| 220 | /* the instance in the mail logs. It is simpler to assign the |
| 221 | /* instance a short name with the "\fB-I \fIname\fR" option. |
| 222 | /* .sp |
| 223 | /* Optional "name=value" arguments specify the instance |
| 224 | /* config_directory, queue_directory and data_directory. |
| 225 | /* For example: |
| 226 | /* .RS |
| 227 | /* .IP |
| 228 | /* .nf |
| 229 | /* # postmulti -I postfix-mumble \e |
| 230 | /* -G mygroup -e create \e |
| 231 | /* config_directory=/my/config/dir \e |
| 232 | /* queue_directory=/my/queue/dir \e |
| 233 | /* data_directory=/my/data/dir |
| 234 | /* .fi |
| 235 | /* .RE |
| 236 | /* .IP |
| 237 | /* If any of these pathnames is not supplied, the program |
| 238 | /* attempts to generate the pathname by taking the corresponding |
| 239 | /* primary instance pathname, and by replacing the last pathname |
| 240 | /* component by the value of the \fB-I\fR option. |
| 241 | /* .sp |
| 242 | /* If the instance configuration directory already exists, and |
| 243 | /* contains both a main.cf and master.cf file, \fBcreate\fR |
| 244 | /* will "import" the instance as-is. For existing instances, |
| 245 | /* \fBcreate\fR and \fBimport\fR are identical. |
| 246 | /* .IP \fBimport\fR |
| 247 | /* Import an existing instance into the list of instances |
| 248 | /* managed by the \fBpostmulti\fR(1) multi-instance manager. |
| 249 | /* This adds the instance to the multi_instance_directories |
| 250 | /* list of the primary instance. If the "\fB-I \fIname\fR" |
| 251 | /* option is provided it specifies the new name for the instance |
| 252 | /* and is used to define a default location for the instance |
| 253 | /* configuration directory (as with \fBcreate\fR above). The |
| 254 | |
|---|